home *** CD-ROM | disk | FTP | other *** search
/ CD-ROM Now 11 / CD-ROM Now MegaDisc 11 (1995-02).iso / utils / ask.doc < prev    next >
Text File  |  1994-10-26  |  8KB  |  234 lines
  1.  
  2.  
  3.                                   ASK, v1.1
  4.                                 -------------
  5.                                 from TifaWARE
  6.  
  7.  
  8.  
  9.  
  10. What's New
  11. ----------
  12.  
  13.  
  14.      With version 1.1 I have substantially reorganized ASK's source code,
  15. placing commonly-used routines in libraries and useful equates and macros
  16. in separate files. From the user's point of view, however, there should be
  17. no change in the program except that ASK no longer allows a space between
  18. '-t' and the time-out value. Sharing code, equates and macros in this way
  19. will make it easier for me to both develop and maintain other assembly
  20. language programs.
  21.  
  22.      Version 1.0 was the first public release of ASK.
  23.  
  24.  
  25.  
  26.  
  27. Introduction
  28. ------------
  29.  
  30.  
  31.      ASK is a simple utility for batch programming. With it you can
  32. execute statements conditionally based on the user's responses to your
  33. questions. And its ability to time-out with no response makes ASK perfect
  34. for "hands-off" batch utilities.
  35.  
  36.  
  37.  
  38.  
  39. Usage
  40. -----
  41.  
  42.  
  43.      Running this program is a breeze.  Assuming you've placed ASK.COM
  44. where DOS can find it, type "ASK -?" to display a brief help message
  45. similar to the following:
  46.  
  47.      TifaWARE ASK, v1.1a, 08/28/90 - ask questions in batch files.
  48.      Usage: ask [-options] [msgtxt]
  49.      
  50.      Options:
  51.        -l  = convert response to lower case
  52.        -tn = wait n seconds before timing out
  53.        -u  = convert response to upper case
  54.        -?  = display this help message
  55.      
  56.      msgtxt is an optional message to display.
  57.  
  58. [If you don't remember anything else from reading the documentation, at
  59. least remember how to display this help message.]
  60.  
  61.      Generally you invoke ASK with some message text. ASK displays the
  62. text and then waits for the user to type a single character. Once a key is
  63. detected, ASK exits with a return code equal to the ASCII character code;
  64. eg, 'Y' = 89, 'N' = 78, '<ENTER>' = 13, '1' = 49, etc... It's then up to
  65. you to check for specific values via the DOS ERRORLEVEL construct in a
  66. batch file.
  67.  
  68.      The actual value returned can be altered using the '-l' ('-u') option
  69. which converts the character to lowercase (uppercase) before ASK exits.
  70.  
  71.      You can instruct ASK to time-out rather than wait indefitely for
  72. input. Simply specify the number of seconds to wait using the '-t' option.
  73. If no input is detected before the time-out is reached, ASK exits with a
  74. return code of 0. Note that with this feature ASK improves on the DOS
  75. PAUSE command. That is, "ASK -t60 Strike a key when ready . . ."
  76. duplicates PAUSE's functionality but waits for input only for a minute! 
  77.  
  78.      All of this may be somewhat confusing so I'll close this section with
  79. an example. Let's say you sometimes, but not always, want to boot your
  80. machine with various memory-resident programs (aka TSRs). You can do this
  81. easily by adding the following code to your AUTOEXEC.BAT file:
  82.  
  83.           rem Check whether to load TSRs
  84.           Ask -t60 -u Load memory-resident programs (Y/n)? 
  85.           if ERRORLEVEL 78 if not ERRORLEVEL 79 goto NoTSRs
  86.  
  87.           rem Load 'em
  88.           Print /d:PRN
  89.           Graphics
  90.  
  91.           :NoTSRs
  92.           rem Set environment variables
  93.           PATH=C:\BIN;C:\USR\BIN
  94.           prompt $p$g
  95.  
  96. Note how ASK is invoked here. ASK displays the text "Load memory-resident
  97. programs (Y/n)? " and waits for up to a minute (60 seconds) for the user
  98. to type a key, which will be converted to uppercase before ASK exits. The
  99. next line is a neat way to test if ERRORLEVEL equals 78, the ASCII
  100. character code for 'N'. Thus, if the user types either an 'N' or 'n' in
  101. response to ASK, execution passes to the label "NoTSRs" and TSRs won't be
  102. loaded. Anything else causes execution to fall through to the next
  103. statement and thereby load TSRs.
  104.  
  105.  
  106.  
  107.  
  108. If You Have Any Trouble
  109. -----------------------
  110.  
  111.  
  112.      ASK will attempt to let you know of any problems that arise.  Here are
  113. the possible error messages and how you should deal with each:
  114.  
  115.      ask: illegal option -- x.
  116.           - Type "ASK -?" for a list of valid options.
  117.  
  118.      ask: time-out value not specified.
  119.           - When you use the '-t' option you must supply
  120.             a time-out value. This number represents the 
  121.             number of seconds to wait for character input
  122.             before aborting ASK.
  123.  
  124.      ask: time-out value too large -- 123456789.
  125.           - The time-out value must be between 0 and
  126.             43199 seconds (12 hours = 43200 seconds). 
  127.  
  128. These messages are written to the standard error device. In this way, they
  129. won't disappear down a pipe or into a file when redirecting ASK's output.
  130.  
  131.      Additionally, ASK uses a return code to convey information about the
  132. success or failure of its operation.  Possible return values are:
  133.  
  134.      Code      Meaning
  135.      ----      -------
  136.      0         Time-out value reached without user input
  137.      1 - 254   ASCII code for character processed
  138.      255       Help message was displayed or time-out was too large
  139.  
  140. You can test for these codes using the ERRORLEVEL variable in a batch file.
  141. Refer to your DOS manual for a table of keys and their ASCII character
  142. codes. 
  143.  
  144.  
  145.  
  146.  
  147. Limitations
  148. -----------
  149.  
  150.  
  151.      To remain portable across all computers running MS-DOS, ASK does not
  152. handle extended scan codes. What this means is that ASK distinguishes only
  153. "typewritter keys"; ie, alphanumeric and punctuation keys. Function keys
  154. or keypad keys lead to unpredictable results.
  155.  
  156.      Keys such as <SHIFT>, <CTRL>, or <ALT> do *not* count as keystrokes
  157. by themselves. They must be used in combination with others.
  158.  
  159.      When a time-out value is specified, ASK adds the value to the current
  160. time and then continually compares the result to the current time until
  161. the two values match. Of necessity, then, the amount of time ASK waits for
  162. user input will be accurate only as long as the system clock does not
  163. change in some abnormal fashion. This might occur if ASK is run in one
  164. DESQview window and the time is changed in another, or if the system clock
  165. loses track of time around midnight while ASK is waiting for input. It's
  166. debatable whether this is appropriate behaviour for ASK.
  167.  
  168.  
  169.  
  170.  
  171. Requirements
  172. ------------
  173.  
  174.  
  175.      TifaWARE ASK runs on machines operating under MS-DOS v2.xx or later,
  176. and requires less than 2K of memory.  It does not use BIOS calls, make
  177. direct writes to video RAM, or otherwise require machines to be
  178. "PC-compatible".  In fact, it will even run properly on a DEC Rainbow!
  179.  
  180.  
  181.  
  182.  
  183. Who Owns It?
  184. ------------
  185.  
  186.  
  187.      I am releasing this implementation of ASK into the public domain. 
  188. Since my involvement with MS-DOS began in 1984, I've been a heavy user of
  189. public domain software.  Public domain software is a terrific idea.  For
  190. the most part, programs are useful and the source code instructive, all at
  191. no cost! With this small contribution to the public domain I hope to pay
  192. back, in some sense, my gratitude to those other programmers who have made
  193. my computing so much easier. 
  194.  
  195.      As a public domain program, ASK carries no obligation on my part to
  196. support users or provide future upgrades.  I have tried to write clean code
  197. and believe it to be "bug-free".  Nevertheless, you must use this program
  198. ***AT YOUR OWN RISK***.  I strongly urge you to scan the source code
  199. yourself, make any desired changes, and recompile the program, if this is
  200. possible.  If you make this standard practice with newly acquired public
  201. domain software, you'll not only protect your system from worms and viruses
  202. but also get a better feel for exactly how each program works!
  203.  
  204.      As author of ASK, I ask of you two things: First, if you distribute
  205. this program, please keep together my original source code, documentation,
  206. and executable.  This just makes it easier for others to use the software. 
  207. Second, let me hear what you think of ASK - your comments on a postcard
  208. would be appreciated. Enjoy!
  209.  
  210.  
  211.  
  212.  
  213. Kudos
  214. -----
  215.  
  216.  
  217.      Many thanks to Borland for its stand-alone debugger, which greatly
  218. reduced the time spent developing this program.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.                           George A. Theall
  225.  
  226.                              TifaWARE
  227.                        506 South 41st St., #3M
  228.                       Philadelphia, PA.  19104
  229.                               U.S.A.
  230.  
  231.                         +1 215 662 0558
  232.  
  233.                 GTHEALL@PENNDRLS.UPENN.EDU (Internet)
  234.